package il.ac.biu.cs.grossmm.api.simple;

import javax.sip.Dialog;

/**
 * Represents SIP-subscrition information
 * 
 */
public interface SipSubscription {

	/**
	 * Gets the back-end internal subscription for this sip subscription.
	 * 
	 * @return the back-end internal subscription for this sip subscription
	 */
	InternalSubscription getInternalSubscription();

	/**
	 * Sets the back-end internal subscription for this sip subscription.
	 * 
	 */
	void setInternalSubscription(InternalSubscription internal);

	/**
	 * Gets the current subscripton state
	 * 
	 * @return the current subscription state
	 */
	SubscriptionState getState();

	/**
	 * Gets the event which caused the most recent subscription state change.
	 * 
	 * @return the event which caused the most recent subscription state change
	 */
	SubscriptionEvent getEvent();

	/**
	 * Get the reason for the event which caused the most recent subscription
	 * state change.
	 * 
	 * @return the reason for the event which caused the most recent
	 *         subscription state change
	 */
	String getReason();

	/**
	 * The time in seconds to retry a subscription. The value has sense only
	 * when the subscription state is TERMINATED. -1 means that the value is not
	 * defined
	 * 
	 * @return the time in seconds to retry a subscription
	 */
	int getRetryAfter();

	/**
	 * Gets the system time (milliseconds since midnight, January 1, 1970 UTC)
	 * of the moment when the subscription will timeout
	 * 
	 * @return the system time (milliseconds since midnight, January 1, 1970
	 *         UTC) of the moment when the subscription will timeout
	 */
	long getTimeoutTime();

	/**
	 * Returns SIP dialog for this SIP subscription
	 */
	Dialog getDialog();

	/**
	 * Returns subscription id (value of the id parameter of the Event header in
	 * the initial SUBSCRIBE message)
	 * 
	 * @return subscription id
	 */
	String getId();

	/**
	 * Return SIP event package, which defines event type for this subscription
	 * 
	 * @return SIP event package, which defines event type for this subscription
	 */
	SipEventPackage getEventPackage();

	/**
	 * Gets package-specific subscription parameters for this subscription
	 * 
	 * @return package-specific subscription parameters for this subscription
	 */
	Object getParam();

	/**
	 * Sets package-specific subscription parameters for this subscription
	 */
	void setParam(Object param);

	/**
	 * Setd SIP dialog for this SIP subscription.
	 * 
	 * @param dialog
	 */
	void setDialog(Dialog dialog);

	/**
	 * Sets susbcription state for this SIP subscription
	 * 
	 * @param event
	 *            the event which caused subscription state transition
	 * @param state
	 *            the new subscription state
	 * @param string
	 *            a human readable reason for the transition
	 */
	void setState(SubscriptionEvent event, SubscriptionState state,
			String string);
}
